#!/usr/bin/env python3
"""
setuptools.setup() 官方文档和学习资源
"""

def official_documentation():
    """官方文档资源"""
    
    print("📚 setuptools.setup() 官方文档和资源")
    print("=" * 50)
    
    resources = [
        ("官方文档", "https://setuptools.pypa.io/en/latest/userguide/", 
         "setuptools 官方用户指南"),
        
        ("API 参考", "https://setuptools.pypa.io/en/latest/references/keywords.html",
         "setup() 函数的所有参数详细说明"),
        
        ("入门教程", "https://packaging.python.org/tutorials/packaging-projects/",
         "Python Packaging Authority 的打包教程"),
        
        ("PEP 517", "https://peps.python.org/pep-0517/",
         "现代构建系统标准"),
        
        ("PEP 518", "https://peps.python.org/pep-0518/",
         "pyproject.toml 标准"),
        
        ("PyPI 分类器", "https://pypi.org/classifiers/",
         "可用的分类器列表"),
        
        ("示例项目", "https://github.com/pypa/sample-projects",
         "Python Packaging Authority 的示例项目"),
    ]
    
    for name, url, description in resources:
        print(f"\n🔗 {name}:")
        print(f"   URL: {url}")
        print(f"   说明: {description}")

def quick_reference():
    """快速参考"""
    
    print(f"\n⚡ 快速参考卡片:")
    print("-" * 25)
    
    quick_ref = '''
最常用的 setup() 参数：

📦 基本信息:
   name="my-package"           # 包名
   version="1.0.0"             # 版本
   description="简短描述"       # 描述
   author="作者名"             # 作者
   author_email="email@..."    # 邮箱

📁 包结构:
   packages=find_packages()    # 自动发现包
   py_modules=["module"]       # 单个模块
   package_data={"pkg": ["*.txt"]}  # 数据文件

🔗 依赖:
   install_requires=["numpy"]  # 运行时依赖
   python_requires=">=3.8"     # Python 版本
   
🚀 入口点:
   entry_points={
       "console_scripts": [
           "cmd=pkg.module:function"
       ]
   }

🔧 C 扩展:
   ext_modules=[Extension(...)]    # C 扩展
   cmdclass={"build_ext": Custom}  # 自定义构建

📊 分类:
   classifiers=[               # PyPI 分类
       "Programming Language :: Python :: 3",
       "License :: OSI Approved :: MIT License"
   ]
    '''
    
    print(quick_ref)

def troubleshooting():
    """常见问题排查"""
    
    print(f"\n🔍 常见问题排查:")
    print("-" * 25)
    
    issues = [
        ("ImportError: No module named 'setuptools'",
         "pip install setuptools wheel"),
        
        ("error: Microsoft Visual C++ 14.0 is required",
         "安装 Visual Studio Build Tools 或使用 conda"),
        
        ("包找不到或版本冲突",
         "检查 install_requires 和 python_requires"),
        
        ("C 扩展编译失败",
         "检查 ext_modules 和 cmdclass 配置"),
        
        ("wheel 构建失败",
         "确保所有依赖都有 wheel 版本"),
        
        ("setup.py 被多次执行",
         "这是正常的，现代构建系统会多次调用"),
    ]
    
    print("问题 -> 解决方案:")
    for problem, solution in issues:
        print(f"\n❓ {problem}")
        print(f"   💡 {solution}")

def your_project_analysis():
    """分析用户项目的 setup.py"""
    
    print(f"\n🎯 你的项目 setup.py 分析:")
    print("-" * 30)
    
    print("""
你的 setup.py 使用了现代最佳实践：

✅ 正确的做法:
   ✓ 条件配置 (has_pyproject_toml)
   ✓ 最小化 setup() 配置
   ✓ 专用的 CMakeExtension 类
   ✓ 自定义 CMakeBuild 命令
   ✓ 声明式扩展配置

📋 当前配置分析:
   ext_modules=[CMakeExtension(...)]  # C++ 扩展
   cmdclass={'build_ext': CMakeBuild} # 自定义构建
   
🔄 构建流程:
   1. pip 调用 setuptools.build_meta
   2. setup() 被执行，传入 'egg_info'
   3. 收集元数据，不编译扩展
   4. 后续调用 'build_ext'，执行 CMakeBuild
   5. 编译 C++ 代码，生成 .pyd/.so

💡 建议改进:
   - 可以添加更详细的错误处理
   - 考虑添加 zip_safe=False
   - 可以添加平台检测逻辑
    """)

def main():
    official_documentation()
    quick_reference()
    troubleshooting()
    your_project_analysis()
    
    print(f"\n" + "=" * 50)
    print("🎓 学习建议:")
    print("   1. 先阅读官方用户指南了解基础")
    print("   2. 查看示例项目学习最佳实践")
    print("   3. 理解 PEP 517/518 的现代构建方式")
    print("   4. 实践中逐步掌握高级配置")
    print("=" * 50)

if __name__ == "__main__":
    main() 